// Copyright (c) 2004-2010 Sergey Lyubka
//
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to deal
// in the Software without restriction, including without limitation the rights
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in
// all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
// THE SOFTWARE.

#ifndef MONGOOSE_HEADER_INCLUDED
#define  MONGOOSE_HEADER_INCLUDED

#ifdef __cplusplus
extern "C" {
#endif // __cplusplus

	struct mg_context;     // Handle for the HTTP service itself
	struct mg_connection;  // Handle for the individual connection

	// Parsed Authorization header
	struct mg_auth_header {
		const char *user, *uri, *cnonce, *response, *qop, *nc, *nonce; // Fields of the Authorization header
		// The following members can be set by MG_AUTHENTICATE callback
		// if non-NULL, will be freed by mongoose
		char *ha1;               // ha1 = md5(username:domain:password), used to compute expected_response
		char *expected_response; // Compared against response
	};

	// This structure contains information about the HTTP request.
	struct mg_request_info {
		void *user_data;       // User-defined pointer passed to mg_start()
		char *request_method;  // "GET", "POST", etc
		char *uri;             // URL-decoded URI
		char *http_version;    // E.g. "1.0", "1.1"
		char *query_string;    // \0 - terminated
		char *remote_user;     // Authenticated user
		char *log_message;     // Mongoose error log message
		long remote_ip;        // Client's IP address
		int remote_port;       // Client's port
		int status_code;       // HTTP reply status code
		int is_ssl;            // 1 if SSL-ed, 0 if not
		int num_headers;       // Number of headers
		struct mg_header {
			char *name;          // HTTP header name
			char *value;         // HTTP header value
		} http_headers[64];    // Maximum 64 headers
		struct mg_auth_header *ah; // Parsed Authorization header, if present
	};

	// Various events on which user-defined function is called by Mongoose.
	enum mg_event {
		MG_NEW_REQUEST,   // New HTTP request has arrived from the client
		MG_HTTP_ERROR,    // HTTP error must be returned to the client
		MG_EVENT_LOG,     // Mongoose logs an event, request_info.log_message
		MG_INIT_SSL,      // Mongoose initializes SSL. Instead of mg_connection *,
		// SSL context is passed to the callback function.
		MG_AUTHENTICATE,  // Authenticate a new HTTP request.  request_info->ah
		// is set, if available.  Callback should fill in request_info->ha1.
	};

	// Prototype for the user-defined function. Mongoose calls this function
	// on every event mentioned above.
	//
	// Parameters:
	//   event: which event has been triggered.
	//   conn: opaque connection handler. Could be used to read, write data to the
	//         client, etc. See functions below that accept "mg_connection *".
	//   request_info: Information about HTTP request.
	//
	// Return:
	//   If handler returns non-NULL, that means that handler has processed the
	//   request by sending appropriate HTTP reply to the client. Mongoose treats
	//   the request as served.
	//   If callback returns NULL, that means that callback has not processed
	//   the request. Handler must not send any data to the client in this case.
	//   Mongoose proceeds with request handling as if nothing happened.
	typedef void * (*mg_callback_t)(enum mg_event event,
			struct mg_connection *conn,
			const struct mg_request_info *request_info);


	// Start web server.
	//
	// Parameters:
	//   callback: user defined event handling function or NULL.
	//   options: NULL terminated list of option_name, option_value pairs that
	//            specify Mongoose configuration parameters.
	//
	// Example:
	//   const char *options[] = {
	//     "document_root", "/var/www",
	//     "listening_ports", "80,443s",
	//     NULL
	//   };
	//   struct mg_context *ctx = mg_start(&my_func, options);
	//
	// Please refer to http://code.google.com/p/mongoose/wiki/MongooseManual
	// for the list of valid option and their possible values.
	//
	// Return:
	//   web server context, or NULL on error.
	struct mg_context *mg_start(mg_callback_t callback, void *user_data,
			const char **options);


	// Stop the web server.
	//
	// Must be called last, when an application wants to stop the web server and
	// release all associated resources. This function blocks until all Mongoose
	// threads are stopped. Context pointer becomes invalid.
	void mg_stop(struct mg_context *);


	// Get the value of particular configuration parameter.
	// The value returned is read-only. Mongoose does not allow changing
	// configuration at run time.
	// If given parameter name is not valid, NULL is returned. For valid
	// names, return value is guaranteed to be non-NULL. If parameter is not
	// set, zero-length string is returned.
	const char *mg_get_option(const struct mg_context *ctx, const char *name);


	// Return array of strings that represent valid configuration options.
	// For each option, a short name, long name, and default value is returned.
	// Array is NULL terminated.
	const char **mg_get_valid_option_names(void);


	// Add, edit or delete the entry in the passwords file.
	//
	// This function allows an application to manipulate .htpasswd files on the
	// fly by adding, deleting and changing user records. This is one of the
	// several ways of implementing authentication on the server side. For another,
	// cookie-based way please refer to the examples/chat.c in the source tree.
	//
	// If password is not NULL, entry is added (or modified if already exists).
	// If password is NULL, entry is deleted.
	//
	// Return:
	//   1 on success, 0 on error.
	int mg_modify_passwords_file(struct mg_context *ctx,
			const char *passwords_file_name, const char *user, const char *password);

	// Send data to the client.
	int mg_write(struct mg_connection *, const void *buf, size_t len);


	// Send data to the browser using printf() semantics.
	//
	// Works exactly like mg_write(), but allows to do message formatting.
	// Note that mg_printf() uses internal buffer of size IO_BUF_SIZE
	// (8 Kb by default) as temporary message storage for formatting. Do not
	// print data that is bigger than that, otherwise it will be truncated.
	int mg_printf(struct mg_connection *, const char *fmt, ...);


	// Read data from the remote end, return number of bytes read.
	int mg_read(struct mg_connection *, void *buf, size_t len);

	// Send a 401 Unauthorized response to the browser.
	//
	// This triggers a username/password entry in the browser.  The realm
	// in the request is set to the AUTHENTICATION_DOMAIN option.
	// If nonce is non-NULL, it is sent as the nonce of the authentication
	// request, else a nonce is generated.
	void mg_send_authorization_request(struct mg_connection *conn, const char *nonce);

	// Get the value of particular HTTP header.
	//
	// This is a helper function. It traverses request_info->http_headers array,
	// and if the header is present in the array, returns its value. If it is
	// not present, NULL is returned.
	const char *mg_get_header(const struct mg_connection *, const char *name);


	// Get a value of particular form variable.
	//
	// Parameters:
	//   data: pointer to form-uri-encoded buffer. This could be either POST data,
	//         or request_info.query_string.
	//   data_len: length of the encoded data.
	//   var_name: variable name to decode from the buffer
	//   buf: destination buffer for the decoded variable
	//   buf_len: length of the destination buffer
	//
	// Return:
	//   On success, length of the decoded variable.
	//   On error, -1 (variable not found, or destination buffer is too small).
	//
	// Destination buffer is guaranteed to be '\0' - terminated. In case of
	// failure, dst[0] == '\0'.
	int mg_get_var(const char *data, size_t data_len,
			const char *var_name, char *buf, size_t buf_len);

	// Fetch value of certain cookie variable into the destination buffer.
	//
	// Destination buffer is guaranteed to be '\0' - terminated. In case of
	// failure, dst[0] == '\0'. Note that RFC allows many occurrences of the same
	// parameter. This function returns only first occurrence.
	//
	// Return:
	//   On success, value length.
	//   On error, -1 (either "Cookie:" header is not present at all, or the
	//   requested parameter is not found, or destination buffer is too small
	//   to hold the value).
	int mg_get_cookie(const struct mg_connection *,
			const char *cookie_name, char *buf, size_t buf_len);


	// Return Mongoose version.
	const char *mg_version(void);


	// MD5 hash given strings.
	// Buffer 'buf' must be 33 bytes long. Varargs is a NULL terminated list of
	// asciiz strings. When function returns, buf will contain human-readable
	// MD5 hash. Example:
	//   char buf[33];
	//   mg_md5(buf, "aa", "bb", NULL);
	void mg_md5(char *buf, ...);

	// read user data from connection
	// required to read user data outside of mongoose.c
	void *mg_read_user_data(struct mg_connection *conn);

#ifdef __cplusplus
}
#endif // __cplusplus

#endif // MONGOOSE_HEADER_INCLUDED
